Release 10.1A: OpenEdge Development:
Java Open Clients

Updating SDOResultSet objects

To update an SDOResultSet object:

Make a change locally in the client application. For example, update column values in an existing row or create a new row (moveToInsertRow()).
Commit the local changes to the database (through the remote SmartDataObject), by executing a row method, such as updateRow() or insertRow().

Caution: If you move the cursor from a row where you updated columns (for example, using next()), before you commit the column updates to the database, your column updates to that row will be lost.

Transactions and concurrency control

By default, all updates that change the database occur in a transaction managed by the remote SmartDataObject. Typically, any method that updates or deletes an existing row, or that inserts a new row causes the SmartDataObject to complete a transaction for that row. Note that updating column values does not, in itself, change the database. Only row operations can actually cause a transaction to occur.

You also can extend a transaction to include modifications to multiple rows by using an SDOResultSet in Batch mode or by remotely controlling an automatic transaction, if one is available on the AppServer. For more information on Batch mode, see the "Using batch mode [extension]" section. For more information on automatic transactions, see the "Using extended transactions" section.

SmartDataObjects use optimistic concurrency control, which means records are read without a lock. Locks are acquired only for the short duration of the transaction when modifications are performed. Before updating or deleting a row, the remote SmartDataObject implementation compares the original values of the columns to their values in the database to determine if the columns were modified by another user. If a column was modified, the modification does not succeed and the transaction is rolled back. A failed update then throws an SDOModificationException. If the SmartDataObject implementation tries to modify or delete a row that is locked, it also throws an SDOModificationException. For more information on SDOModificationException, see the "Errors and exceptions" section.

Updating column values

The following methods modify a column in an SDOResultSet according to the specified data type. All column access methods in SDOResultSet use the flat model (see OpenEdge Development: Open Client Introduction and Programming ). The column is specified by name (columnName) or number (columnIndex) and is set to the specified value (value):

void updateBigDecimal(int columnIndex, BigDecimal value)
void updateBigDecimal(String columnName, BigDecimal value)
void updateBlob(int columnIndex, java.sql.Blob value)
void updateBlob(String columnName, java.sql.Blob value)
void updateBoolean(int columnIndex, boolean value)
void updateBoolean(String columnName, boolean value)
void updateBytes(int columnIndex, byte x[])
void updateBytes(String columnName, byte x[])
void updateClob(int columnIndex, java.sql.Clob value)
void updateClob(String columnName, java.sql.Clob value)
void updateDate(int columnIndex, java.sql.Date value)
void updateDate(String columnName, java.sql.Date value)
void updateDouble(int columnIndex, double value)
void updateDouble(String columnName, double value)
void updateInt(int columnIndex, int value)
void updateInt(String columnName, int value)
void updateLong(int columnIndex, long value)
void updateLong(String columnName, long value)
void updateNull(int columnIndex)
void updateNull(String columnName)
void updateObject(int columnIndex, Object value)
void updateObject(String columnName, Object value)
void updateString(int columnIndex, String value)
void updateString(String columnName, String value)
void updateTimestamp(int columnIndex, java.sql.TimeStamp value)
void updateTimestamp(String columnName, java.sql.TimeStamp value)

Some java.util.Date and java.sql.Date methods are being deprecated by JavaSoft in favor of using the more robust java.util.GregorianCalendar. These are the methods that update column values with instances of this class:

void updateGregorianCalendar(String columnName, GregorianCalendar date) [Extension]
void updateGregorianCalendar(int columnIndex, GregorianCalendar date) [Extension]

For more information on the mapping between 4GL and Java data types for SQL ResultSet applications, see Appendix C "Passing Temp-tables as SQL ResultSet Parameters."

Inserting, deleting, and updating rows

The methods in Table 9–2 manage operations on rows in the SDOResultSet.

Table 9–2: Managing operations on SDOResultSet rows 

Method	Description
boolean rowDeleted()	Returns true if the cursor is positioned on a deleted row, whether or not the deletion is sent to the AppServer because it does not make sense to allow the user to manipulate a row that is logically deleted. The only time the row is not also physically deleted on the AppServer is if you are using a batch update. For more information, see the "Using batch mode [extension]" section.
boolean rowInserted()	Returns true if the cursor is positioned on an inserted row position and the row is not yet sent to the AppServer.
boolean rowUpdated()	Returns true if the cursor is positioned on a row that is modified but not yet sent to the AppServer.
void CancelRowUpdates()	Cancels the updates by rolling back the effects of all method calls that updated column values. To cancel these updates, you must invoke this method before any call to updateRow() or insertRow().
void deleteRow()	Deletes the row in the current position and sends the delete request to the AppServer.
void insertRow()	Sends the newly created row to the AppServer.
void moveToCurrentRow()	Moves the cursor from the insert row back to the current position.
void moveToInsertRow()	Moves the cursor to a staging position for creating a new row.
void updateRow()	Sends the updates for the current row to the AppServer.

Using extended transactions

As described earlier, by default, each row modification (row update, insertion, and deletion method) executes as a single transaction in the SmartDataObject. You can extend a transaction to include multiple rows using Batch mode, where a sendBatch() method applies a set of row updates as a single transaction (see the "Using batch mode [extension]" section). You also can explicitly manage a larger transaction on the AppServer remotely, using an automatic transaction.

An automatic transaction allows you to remotely create a larger transaction within which all SmartDataObject transactions become nested as subtransactions. Using an automatic transaction, the Open Client application can start, commit, and roll back a single transaction by executing methods on a special ProcObject defined in the same AppObject that provides access to the corresponding SmartDataObject. The persistent procedure underlying this ProcObject supports specific functionality and must be available for execution on the AppServer to make an automatic transaction possible. Such a transaction can encompass the entire life of the SDOResultSet. For more information on automatic transactions, see OpenEdge Application Server: Developing AppServer Applications .

Note: You should call reOpenQuery() after an explicit transaction roll-back, to maintain a cache that is consistent with the database. The reOpenQuery() method also can be desirable after committing a transaction containing inserted rows, so these rows are visible within the ResultSet. For more information, see the "Visibility of updates" section.

Using batch mode [extension]

Batch mode allows an Open Client to send several updates to the AppServer in one transaction. Depending on your application requirements, this might be a better update strategy than generating a transaction for each update method:

If your application requires user feedback for each update method applied, you generally must complete a transaction for each update method and Batch mode is not appropriate.
If your application requires that a group of updates be applied and succeed together, you must group the updates into a single large transaction. You can do this by using an automatic transaction or by using Batch mode. For information on automatic transactions, see OpenEdge Application Server: Developing AppServer Applications .
If your application has the option of applying several updates individually or as a group, you can generally increase performance dramatically by grouping the updates into a single large transaction using Batch mode.
If your SDOResultSet is in Stateless mode, you can apply modifications only under Batch mode.

Table 9–3 lists the SDOResultSet methods that support Batch mode.

Table 9–3: SDOResultSet methods that support Batch mode

Method	Description
void cancelBatch() [Extension]	Undoes all the modifications of the current batch.
void sendBatch() [Extension]	Sends the current batch to the AppServer.
void sendBatchAndReOpen() [Extension]	Sends the current batch to the AppServer, then reopens the ResultSet. In Stateless mode, this method is more efficient than separately calling sendBatch() and reOpenQuery(). For more information, see the "Visibility of updates" section.
void startBatch() [Extension]	Starts a batch session. All the modifications (column updates, deletions and insertions) are maintained locally. Calling this method if you have already called it and have not called sendBatch() or cancelBatch() throws an Exception.
boolean inBatch() [Extension]	Returns true if the SDOResultSet object is in Batch mode (that is, you have called startBatch() and have not yet called sendBatch() or sendBatchandReopen()). Note: A row that is updated or deleted in Batch mode, and has not yet been sent to the AppServer (using sendBatch()), cannot be refreshed using refreshRow(). Also, to save your changes locally in batch mode, you must still call the row update methods (for example, insertRow() or updateRow()) even though, in this mode, your changes are not sent to the AppServer.

Visibility of updates

The visibility, from within the Open Client, of an update to the SDOResultSet object depends on whether the update is applied by:

The Open Client itself.
An external application working on the same data source that feeds the SDOResultSet.

The following rules determine the visibility of updates initiated by the Open Client:

Column updates — Column updates are visible.
Row inserts — New rows are invisible until the ResultSet is reopened.
Row deletion — Row deletions are visible.

Updates by external applications typically can occur on the data source that feeds the SDOResultSet. You can make any such updates visible to the Open Client application by calling reOpenQuery(), which refreshes all data in the SDOResultSet. If you do not call reOpenQuery(), however, the following rules determine the visibility of updates from external applications:

Column updates — The modification of a column by another application can be made visible by calling the refreshRow() method.
Row inserts — Row inserts are not visible in PREFETCH mode. In other scrolling modes, the visibility is determined by a combination of the underlying implementation of SmartDataObject and the 4GL query. The guideline is that the application should not make any assumptions unless it makes an explicit call to reOpenQuery().
Row deletion — Row deletions are not visible in PREFETCH scrolling mode. In other scrolling modes, the visibility is determined by a combination of the underlying implementation of the SmartDataObject and the 4GL query. The guideline is that the application should not make any assumptions unless it makes an explicit call to refreshRow() or reOpenQuery(). In these cases, the specific row deletion or all the row deletions become visible, respectively.